//
//  ZegoUIKitPrebuiltLiveStreamingManagerProtocol.swift
//  ZegoUIKitPrebuiltLiveStreaming
//
//  Created by zego on 2024/1/17.
//

import Foundation

/// 定义直播管理相关的操作接口，实现该协议的类可以对直播过程中的各种操作进行管理，如房间管理、PK 对战管理等
public protocol LiveStreamingManagerApi {
    
    /// 添加直播事件监听器，用于监听直播过程中的各种事件
    /// - Parameter delegate: 实现了 `ZegoLiveStreamingManagerDelegate` 协议的观察者对象，用于接收直播事件通知
    ///
    /// Add live event listener
    /// - Parameter delegate: Observer
    func addLiveManagerDelegate(_ delegate: ZegoLiveStreamingManagerDelegate)
    
    /// 获取当前直播房间的房主 ID
    /// - Returns: 房主的唯一标识符，如果不存在则返回空字符串
    ///
    /// Get host ID
    /// - Returns: host id
    func getHostID() -> String
    
    /// 判断指定用户是否为当前直播房间的房主
    /// - Parameter userID: 用户的唯一标识符
    /// - Returns: 如果该用户是房主则返回 `true`，否则返回 `false
    ///
    /// Is the user a host?
    /// - Parameter userID: Unique identifier for the user
    /// - Returns: The result 'true' indicates that the person is a host, while 'false' indicates that they are not.
    func isHost(_ userID: String) -> Bool
    
    /// 判断当前本地用户是否为当前直播房间的房主
    /// - Returns: 如果当前本地用户是房主则返回 `true`，否则返回 `false`
    ///
    /// Is the current user a host?
    /// - Returns: The return result 'true' represents yes, while 'false' represents no.
    func isCurrentUserHost() -> Bool
    
    /// 判断当前本地用户是否为连麦者
    /// - Returns: 如果当前本地用户是非房主且摄像头或麦克风处于开启状态则返回 `true`，否则返回 `false
    ///
    /// Is the current user a cohost?
    /// - Returns: The return result 'true' represents yes, while 'false' represents no.
    func isCurrentUserCoHost() -> Bool
    
    /// 发送停止 PK 对战的请求，用于结束当前正在进行的 PK 对战
    ///
    /// Sending stop pk request
    func stopPKBattle()
    
    /// 接受来自其他房主的 PK 对战邀请，并携带自定义数据
    /// - Parameters:
    ///   - requestID: PK 对战请求的唯一标识符，用于标识该请求
    ///   - anotherHostLiveID: 发起邀请的另一个房主的直播 ID
    ///   - anotherHostUser: 发起邀请的另一个房主的用户信息
    ///   - customData: 自定义数据，可用于传递额外的业务信息，如比赛规则、奖励等
    ///
    /// Accept PK invitation
    /// - Parameters:
    ///   - requestID: Unique ID for PK request
    ///   - anotherHostLiveID: Sender's live ID
    ///   - anotherHostUser: Sender
    ///   - customData: Custom data
    func acceptIncomingPKBattleRequest(_ requestID: String, anotherHostLiveID: String, anotherHostUser: ZegoUIKitUser, customData: String)
    
    /// 接受来自其他房主的 PK 对战邀请，不携带自定义数据
    /// - Parameters:
    ///   - requestID: PK 对战请求的唯一标识符，用于标识该请求
    ///   - anotherHostLiveID: 发起邀请的另一个房主的直播 ID
    ///   - anotherHostUser: 发起邀请的另一个房主的用户信息
    ///
    /// Accept PK invitation
    /// - Parameters:
    ///   - requestID: Unique ID for PK request
    ///   - anotherHostLiveID: Sender's live ID
    ///   - anotherHostUser: Sender
    func acceptIncomingPKBattleRequest(_ requestID: String, anotherHostLiveID: String, anotherHostUser: ZegoUIKitUser)
    
    /// 拒绝来自其他房主的 PK 对战邀请
    /// - Parameter requestID: PK 对战请求的唯一标识符，用于标识要拒绝的请求
    ///
    /// Refuse PK invitation
    /// - Parameter requestID: Unique ID for PK request
    func rejectPKBattleStartRequest(_ requestID: String)
    
    /// 控制是否静音另一个房主的音频
    /// - Parameters:
    ///   - mute: `true` 表示静音另一个房主的音频，`false` 表示接收其音频
    ///   - callback: 操作结果的回调，当操作完成时会调用该回调函数，返回操作结果
    ///
    /// Whether to block audio from other host
    /// - Parameters:
    ///   - mute: true represents blocking, while false represents receiving.
    ///   - callback: Callback of operation result
    func muteAnotherHostAudio(_ mute: Bool, callback: ZegoUIKitCallBack?)
    
    /// 向另一个房主发送 PK 对战邀请，并携带自定义数据
    /// - Parameters:
    ///   - anotherHostUserID: 被邀请的另一个房主的用户 ID
    ///   - timeout: 请求的超时时间，单位为秒，默认值为 60 秒
    ///   - customData: 自定义数据，可用于传递额外的业务信息，如比赛规则、奖励等
    ///   - callback: 请求结果的回调，当请求处理完成时会调用该回调函数，返回错误码和请求 ID
    ///
    /// Send PK invitation
    /// - Parameters:
    ///   - anotherHostUserID: Inviting user's ID
    ///   - timeout: Request timeout limit, Default value is 60 seconds
    ///   - customData: Custom data that needs to be passed.
    ///   - callback: Callback for request results
    func sendPKBattleRequest(anotherHostUserID: String,
                                    timeout: UInt32,
                                    customData: String,
                                    callback: UserRequestCallback?)
    
    /// 向另一个房主发送 PK 对战邀请，不携带自定义数据
    /// - Parameters:
    ///   - anotherHostUserID: 被邀请的另一个房主的用户 ID
    ///   - timeout: 请求的超时时间，单位为秒，默认值为 60 秒
    ///   - callback: 请求结果的回调，当请求处理完成时会调用该回调函数，返回错误码和请求 ID
    ///
    // Send PK invitation
    /// - Parameters:
    ///   - anotherHostUserID: Inviting user's ID
    ///   - timeout: Request timeout limit, Default value is 60 seconds
    ///   - callback: Callback for request results
    func sendPKBattleRequest(anotherHostUserID: String, timeout: UInt32,callback: UserRequestCallback?)
    
    /// 取消已经发送的 PK 对战请求
    /// - Parameters:
    ///   - customData: 自定义数据，可用于传递额外的业务信息，如取消原因等
    ///   - callback: 取消操作结果的回调，当取消操作完成时会调用该回调函数，返回错误码和请求 ID
    ///
    /// Cancel pk request
    /// - Parameters:
    ///   - customData: Custom data that needs to be passed
    ///   - callback: Cancelled result callback
    func cancelPKBattleRequest(customData: String?, callback: UserRequestCallback?)
    
    /// 离开当前直播房间，会清理相关资源并停止可能正在进行的 PK 对战等操作
    ///
    /// Leave the room
    func leaveRoom() 
}
